Languguage OS 2/Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO/language/pcpil/pidoc2.txt

Text File | 1994-03-01 | 40KB | 1,042 lines

DISK OR NETWORK FILES

To open a disk or network file the format of the FX: statement is as follows:

       FX:pathname

Where the word pathname represents the name of the disk file or network node
you wish to connect to. The pathname is formed per DOS file name conventions
for specifying drive, directory, root file name, and file suffix. If the file
exists, then it is made available for the PILOT program to read from or write
to. If the named file does not exist, then the FX: statement automatically
creates a file with that name, containing zero bytes of data. The file is
made available to read from or write to. The FIZ function may be used to
determine whether a file exists prior to attempting to open it.

A disk file can be thought of as a list of bytes numbered from 0, for the
first byte, up to the size of the file. To read data from the file use the
FI: statement as shown above. The position-expression is evaluated to a
number.  The number represents an offset from the beginning of the file where
reading is to begin. The byte at the specified location in the file is the
first byte read into the string variable.  The number of bytes copied into
the string variable is equal to the maximum length established for the string
variable when it was created. If the FI: statement attempts to read beyond
the length of the disk file, then the string variable is padded out with
CHR(255) characters to its maximum length.

EXAMPLE 1: Open a disk file named DATA, read 20 bytes from the file, starting
at byte position 15.

       D: B$(20)
       FX: DATA
       FI:15,B$

The FO:, or FILE OUT statement can be used to write data into a disk file.
The position-expression determines the byte offset in the file where data is
first written. The number of bytes written to the file is equal to the length
of the data expression on the FO: statement.

In using disk files you can think of the disk file as a long string of bytes.
Each byte is addressable by its byte offset from the file start. However, it
is often convenient to think of the file as a series of records, each record
being a pre-determined number of bytes in length. For example, assume that
your goal is to keep a file of student names and scores. You may decide that
the file will consist of a series of 50-byte records. Each one would hold the
name and score for one student. Also assume that in the first record of the
file is the number of the next available record in the file.  The following
program examples show how to set this file up initially and how to write a
record into the file. This example illustrates the use of the file
statements.  In practice, you would use KEEP to simplify the task.

EXAMPLE 2: create file to save student scores

       FX:RECORDS        (create file named RECORDS)
       FO:0,"  1"        (write 1 into the first record)

EXAMPLE 3: save a student name and score in the RECORDS file

       R: set up strings
       D:NAME$(30),REC$(50),X$(3)
      . . .  program runs here, assume that student
      . . .  name is stored in NAME$, and score is
      . . .  in the numeric variable SCORE
       R: construct student record with trailing
       R: CR and LF characters
       C:REC$(49,2) = CHR(13) !! CHR(10)
       C:REC(1,30) = NAME$
       C:REC(31,18) = SCORE
       R:determine next available record
       FX:RECORDS
       FI:0,X$
       FO:X$,REC$
       R:update record number at the start of file
       C: X$(1,3) = X$ + 1
       FO:0,X$
       FX:

PRINTER OR AUXILIARY PORT FILES

The system printer device, or the auxiliary RS-232 serial interface can be
accessed as a PILOT file.  These special files can be used for output only.
To open the printer as a file use:

       FX:PRN:

To open the serial interface as a file use:

       FX:AUX:

The serial interface can be used as a simple control mechanism for video disc
or other external devices which have an RS-232 interface.  One consideration
for such devices is that both the computer and the other device must be set
up to communicate at the same baud rate (speed).  The baud rate on the
computer end is set up prior to starting your PILOT program by issuing the
DOS MODE command. This command could be placed in your AUTOEXEC.BAT file so
that it happens each time the computer is turned on. A sample MODE command to
set the baud rate to 1200 baud might look like this:

       MODE COM1:1200,N,8,1

See the DOS manual for further information on the MODE command.

Once open, the FO: statement may be used to write data to the printer or to
the device attached to the serial interface. The format of the FO: statement
is:

       FO:0,expression

The "0" is ignored for these devices. The string value of the expression is
written to the device. No extra control characters are automatically written
after the expression value. If you wish to transmit a RETURN or LINE FEED
after the data, you must append these characters to the data.

EXAMPLE 4: Write a line to the printer, then space the printer up one line.

       FX:PRN:
       FO:0,"Hello world." !! CHR(13) !! CHR(10)


EXAMPLE 5: Control Video Disc Player From PILOT.  This example assumes that a
Pioneer LDV-700 and Pioneer IU-04 interface is attached to the serial
interface and that the baud rate has been set via a MODE command prior to
running the PILOT program.

       FX:AUX:
       R: next play frame 1000 as still frame
       FO:0,"F1000SI" !! CHR(13)
       R: next line plays 5 sec from frame 2345
       FO:0,"F2345SP@5" !! CHR(13)
       R: next line turns off video disc
       FO:0,"Q" !! CHR(13)

The actual command strings written to the video disc player by the above FO:
statements may change for another brand or model of disc player. But the
method used in PILOT to control the device is the same for any device which
has a serial, RS-232 interface.

HEAP FILE

The heap facility permits the PILOT program to make use of very large
computer memory as a temporary, very fast file. The program creates a heap
out of otherwise unused RAM. Once the heap is created the program can write
string data to the heap, and read it back later in the program.  In effect
the heap becomes an unlimited extension to the program string space.  When
the program ends and returns to DOS the contents of the heap are discarded.

To establish the heap execute the following statement once at the beginning
of the program use:

       FXH: n

where n is a number indicating the size, in bytes, to be set aside for the
heap. An XSPACE error occurs if the amount is to great for the system in use.

To estimate the maximum size of the heap for a particular system proceed as
follows. From DOS before running PILOT run CHKDSK to get the amount of unused
memory. From that subtract 182K for PILOT. The remainder is available. If the
program is to call other programs or languages (via EXEC) you must leave
sufficient unused space for those programs.

Only the first successful FXH: statement has an effect. Once the heap is set
up, other FXH: statements are ignored.

The heap does not count as the one allowed open file. So even though the heap
is in use one additional disk file may be open.

To write data to the heap use the following:

       FOH: n,string-value

where n is the byte position within the heap at which the string-value is to
be written. The first byte position in the heap is location 0.  The string
value may be a string variable name or any string expression.

To retrieve the data into a string variable again use the statement:

       FIH: n,V$

where n is the position in the heap from which the data is to be read, and V$
is any string variable name.

The statements FOH: and FIH: work exactly like FO: and FI: for disk files.
The difference is that writing and reading the heap is very fast, taking no
more time than a simple assignment statement. The heap can serve as a quick
access storage bin for sprite tables, graphic images, machine language
subroutines, etc.

Items to be loaded from disk files into the heap must be moved there through
string variables by reading from disk to the string via FI:, then writing to
the heap from the string via FOH:.

EXAMPLE 6: Create a heap and move two  graphic images to the heap.

       FXH: 30000
       DX:P$(10000)
       FX:PIC1.SQZ
       FI:0,P$
       FOH:0,P$
       FX:PIC2.SQZ
       FI:0,P$
       FOH:10000,P$

EXAMPLE 7: display a graphic image from the heap

       FIH:10000,P$
       V:P$

See also:  AUX(0) function,  FIZ function,  MODE (DOS manual)

GRAPHICS - display graphic images

       G: turtle-graphics-command-list
       GX: graphics-image-filename
       GSX: graphics-image-filename

The GRAPHICS statement is used to control the graphics screen display. There
are several types of graphics which can be used:

TURTLE GRAPHICS: to draw colored points, lines, and shapes either by absolute
pixel coordinates or by directing an invisible "turtle" to walk in various
directions while drawing a line wherever it has gone.  Turtle graphics in
PILOT is similar to what is found in the LOGO language.

IMAGE GRAPHICS: a graphics image is a stored picture or full screen graphic
that has been created outside of the PILOT program and stored in a disk file.
The GX: statement can display such a picture by painting the entire image on
the screen in one operation.

SCREEN SAVE/RESTORE: To facilitate the creation of dialog boxes, pull-down
menus, and other types of screen overlays, the GSX: and GX: statement provide
a way to take a snapshot of the screen, save it in internal memory, then
instantly put the screen back as it was on command.

SPRITE GRAPHICS: a sprite is a smaller picture which can be placed anywhere
on the screen or can be moved around (animated) on the screen by attaching it
to the turtle, and allowing the turtle to "drag" it around on the screen.

TURTLE GRAPHICS

The turtle graphics commands are valid only for graphic screen modes, namely
modes 4, 5, 6, 13, 14 and 16.

The G: statement is used for turtle graphics.  After the colon you can write
a list of turtle graphics commands. The list can contain one or more of the
following commands, separated by ";" characters.  To draw lines you tell the
(invisible) turtle which direction to head and how far to walk.  As the
turtle walks it can leave a colored line on the screen.  The turtle's heading
ranges from 0 degrees (straight up) to 359 degrees with the heading angle
increasing as it rotates to the right.  If the turtle walks off the screen it
comes back on the opposite edge.  In the command descriptions below n
represents a numeric variable, an integer constant, or an expression enclosed
in parentheses.

Ar,d - arc or circle

Draw an arc with radius of r turtle steps, starting at the angle equal to the
turtle heading, and sweeping through an angle of d degrees. The turtle
heading rotates right by d degrees, the turtle location remains unchanged. If
d=360 a circle is drawn

Bx,y - solid color bar

Draws a bar, or solid box, with the upper left corner at the turtle location,
x and y are the number of pixels across and down of the bar.  The turtle is
moved to one pixel down and to the right of the bar.

Pn - paint an area

Paints an area to color number n. The painted area starts at the turtle
location and includes all adjacent pixels with the same color as the starting
pixel. It is a flood fill which recursively wraps around all corners and
shapes as necessary.

Hn - set turtle heading to n degrees

Rn - rotate turtle heading right n degrees

Ln - rotate turtle heading left n degrees

Fn - walk forward n steps

Gx,y - set turtle location to pixel x,y

Dx,y - draw a line to pixel location x,y

Cn - set line color for F or D to n (0-3)

Cn,w - set line color and line width

The width can be set to 0 (no line), 1, 2 or 3.  The default is a 1 pixel
wide line.  The  line width affects  draw, forward, and arc commands.

E - erase screen to background color

*n(...) - repeat the enclosed commands n times

Wn - wait, or delay n 60ths of a second

Xn - set horizontal scale factor

Yn - set vertical scale factor

S var$ - make string variable var$ the current sprite table

Sn - sprite select

Display, or erase sprite n, and attach sprite n to the turtle.

S0 - detach sprite from the turtle

Jn - jump back to a previous sprite

Move turtle to location of sprite n and attach sprite n to the turtle.

MODES AND COLORS

Turtle graphics can be performed in modes 4,5,6,13,14 and 16. In modes 4 and
5 the screen is 320 pixels  across by 200 down with valid line colors 0-3.
Color 0 selects the current background color as set by TYPE SCREEN.  Colors
1, 2 and 3 are determined by the current mode. See the TYPE SCREEN statement
for more information on modes and colors.

MODES 4 and 5: 320 x-pixels, 200 y-pixels, colors 0-3
MODE 4 COLORS: 1-green, 2-red, 3-yellow
MODE 5 COLORS: 1-cyan, 2-magenta, 3-white

Background color for modes 4 and 5 is color number 0. It can be selected from
colors 0-15, with two possible intensities as documented under TYPE SCREEN.

In mode 6 the screen is 640 pixels across by 200 down with one valid line
color as set by the TS:Xn command.

MODE 6: 640 x-pixels, 200 y-pixels, colors 0-1

With an EGA (Extended Graphics Adapter) the additional graphics modes are:

MODE 13: 320 x-pixels, 200 y-pixels, colors 0-15

MODE 14: 640 x-pixels, 200 y-pixels, colors 0-15

MODE 16: 640 x-pixels, 350 y-pixels, colors 0-15

SCALE FACTORS

The X and Y scale factors can be adjusted for a particular display to achieve
uniformity in horizontal and vertical step sizes.  The default value is X1;Y1
, which makes a turtle step size equal to one quarter of a pixel.  To make a
step equal to a pixel set the values to X4;Y4.

Scale factors can also be used to change the aspect ratio between x and y
directions as shown in the ellipse example below.

EXAMPLE 1: Turtle graphics examples.

G: *18(F60;R20)        draws a circle

G: *4(F80;L90)         draws a box

G: C2;*5(F160;R144)    draws a red star

G: X6;Y3;*36(F10;R10)  draws an ellipse

G: G10,20;D15,85       line (10,20)-(15,85)

G: G(X+30),40;F(60*D)  expressions as arguments

G: A50,360;P2          a circle, filled in

G: B20,20;B40,40       two bars

G: C1,3;A50,180        a wide-line semi-circle



IMAGE GRAPHICS

A graphics image can be created by the GIE program or by other graphics
creation products which can produce a 16K bit-mapped screen image, often
called BSAVE/BLOAD format. Many useful graphics creation products do not use
the BSAVE/BLOAD format to store pictures on disk.  However, in these cases
there is often a conversion process that can be used to convert the picture
files to BSAVE/BLOAD format. The BSAVER utility may be useful doing this type
of conversion. See also: Appendix C.

To load a graphics image from a disk file and display it on the screen, first
insure that the screen is in a graphics mode (4,5 or 6) and set the desired
background color (if not already set). The following statement shows how to
do these two things:

       TS:M4;B2

Then execute the following command:

       GX:filename

PILOT can also save the current screen  display in a disk file by the
following command:

       GSX:filename

The GX: and GSX: statements may also be used in text modes (0 though 3). The
screen image file produced is 2K for 40 column screens or 4K for 80 column
screens.  Prior to executing a GX: statement to display a text screen, the
screen mode must be set to the same mode in which the screen image was saved
via a previous GSX: statement.

The PIQ utility program may also be of interest when using image graphics. It
can be used to compress a graphics image from BSAVE/BLOAD format into a
compact format which takes up less disk space and displays more quickly. PIQ
also provides for various screen wipes and special effects for partial or
complete screen images. See also: Appendix C.

SCREEN SAVE/RESTORE

The GSX: statement can be used to make a copy of the current screen in ram
memory. The command format is:

       GSX:           (no arguments follow the colon)

This command happens instantaneously, so it is useful for saving the screen
display when the program is to be interrupted for a menu, dialog box, or
other student-invoked control function.

Once the screen has been saved, the program can modify the screen as
necessary to converse with the student. This might involve the display of a
menu box, help screen, note pad, calculator, or glossary.  When the auxiliary
function is complete, the screen can be restored to its original state by the
command:

       GX:           (no arguments follow the colon)

The screen restore is instantaneous. Not only is the visual data put back as
it was, but the cursor location, colors, and current and previous viewport
data is put back as well. It is, however, up to the program to insure that
prior to execution of the GX: statement, the screen mode is set to the screen
mode that existed at the time of the GSX: statement. If the mode has not
changed in the interim, then it need not be changed back again. But if the
screen mode did change after the GSX: statement, then it must be changed back
by the TS:Mn command just prior to the GX: statement. The MOD built-in
function may be useful in determining the screen mode prior to the GSX:
statement if it is not already known.

Unlike other uses of the Graphics statement, the uses of GSX: and GX: are
valid in any screen mode from 0 to 6.

EXAMPLE 2: SYSX routine using GSX: and GX:

       R: come here when user pushes ESC key
       *SYSX
       GSX:
       TS:V10,30,5,11
       TX:*******************
         :
         :  M  -  Main menu
         :  C  -  Calc
         :  G  -  Glossary
         :
         :*******************
       AS:
       M:M!m
       JY:MENU
       M:C!c
       JY:CALC
       M:G!g
       JY:GLOSS
       *SYSX2
       GX:
       E:

       *CALC
       TX:Input expression
       :such as  123.5 * 7
       :or ENTER to return
       A:
       J(%B=" "):SYSX2
       X:"C:Z=" !! %B
       T:#Z
       W:30
       J:CALC

       *GLOSS
       TX:Glossary...
      ...
       W:100
       J:SYSX2

SPRITE GRAPHICS

A sprite is a picture, similar to a graphics image, except that a sprite is
smaller. A graphics image is 320 pixels across by 200 pixels up and down (the
entire screen). A sprite can range from 32 pixels by 32 pixels, to 64 pixels
by 128 pixels. Sprites can be displayed in graphics modes 4, 5 and 6 only.

A sprite can be used as a way to draw diagrams or pictures on the screen. One
of the unique features of a sprite is that it can be animated or moved on the
screen. This is accomplished by use of the turtle graphics commands of the G:
statement. To move a sprite you need only "attach" the sprite to the turtle,
then move the turtle via forward or draw commands. As the turtle moves,
rather than drawing a line as it usually would, it moves the sprite along
with it on the screen. To take it a step further, you can move several
sprites apparently at the same time by telling the turtle to take turns
jumping from one sprite to the next, moving each a little bit on each turn.

The use of sprites is discussed in great detail in the section of this
document entitled "Sprites".

JUMP - goto a destination

       J: label
       J: #variable
       J: @A
       J: @P
       J: @-P
       J: @M

Unless otherwise instructed, PILOT executes each statement in your program
one after the other, in the exact order that the statements are written. With
the JUMP statement you can alter this order by branching to a specified
location. The location can be a statement label, a numeric variable, or one
of four possible special destinations which are commonly needed.

JUMP TO A LABEL

The first form of the JUMP statement above transfers control to the statement
following the specified label. Although the statement label in the program is
preceded by an "*", you do not put the "*" character on the JUMP statement.

EXAMPLE 1: jump to a label

       J:PART4
       . . .
      *PART4 T:This is chapter 4.

If the label name to which the program should jump is contained in a string
variable, use the Execute Indirect statement to perform the jump as shown in
this example.

EXAMPLE 2: jump to a string variable, say X$:

       X:"J:" !! X$

or if the jump is to be conditional:

       X(condition):"J:" !! X$

JUMP TO A NUMERIC VARIABLE

The second format shown above permits a jump to a location stored in a
numeric variable. This is a special purpose use which can be used in only one
way. The numeric variable used in the Jump can be set by the statement:

       C: X = %E

which sets variable X to the jump location of the return point from the most
recent Use statement. Then to jump to this location use:

       J: #X

This special case Jump is used only in the construction of an Escape routine
which links to another module then expects to return to the point from which
the escape routine was called.


JUMP TO LAST ACCEPT STATEMENT

The third form of the JUMP shown above is used to branch back to the last
ACCEPT statement that was executed. This is useful to allow the student to
re-answer the question just answered.

EXAMPLE 3: jump to last ACCEPT

       T:What is 2+3?
       A:
       M:5
       TY:Right
       TN:No, try again
       JN:@A


JUMP TO THE NEXT MATCH

When a student response is evaluated, there is sometimes a series of MATCH
commands to test for various correct and incorrect possibilities.  After each
MATCH might be a series of statements to be executed if the MATCH is YES.
Otherwise it is convenient to jump directly to the next MATCH to check for
the next possibility.

EXAMPLE 4: jump to next MATCH

       M:calcium
       JN:@M
       . . .
       M:silicon
       JN:@M
       . . .
       M: . . .


JUMP TO NEXT PROBLEM

If a program consists of a set of questions or problems, presented one after
the other, it can be convenient to start each question section with the P:
statement. Then, from anywhere within the previous question, the program can
branch to the next problem without having to place a label on each question.

EXAMPLE 5: jump to next problem

       M:Italy
       TY:Right, let's go on.
       JY:@P
       . . .
       P:
       T:Question 14.
       T:...


JUMP TO LAST PROBLEM

The final format of the Jump permits the program to jump back to the last
Problem statement passed. This could be useful in going back to the start of
the current section or when going back to accept another answer when the
cursor must be positioned prior to letting the student answer again.

EXAMPLE 6: jump to last Problem

       P:
       TS:G10,5;F4;B1
       A:
       . . .
       J:@-P

See also:  STATEMENT LABELS


KEEP RECORDS - save data on disk

       K: expression

The KEEP statement  provides a simple way to write data to a disk file for
later manipulation. It can be used to store student progress records, scores,
remarks from the student to the author, student answers, etc. The file
written by the KEEP statement is a text file which can be displayed by the
DOS TYPE command or examined by a text editor, such as EZ. It can also be
read by another program to perform statistics or other reporting.

The default file name used to store data written by the KEEP statement is
K.REC, but the K option of the PROBLEM statement can be used to specify any
filename, pathname, or network file name to be used instead. You need not
take any action to create the keep file prior to running the PILOT program.
If it does not exist, the KEEP statement automatically creates the file.

Each time the KEEP statement is executed, the string value of the expression
after the colon is written to the current keep file.  A new-line sequence is
appended to the string expression as it is written to the file. This means
that each KEEP adds one text line to the keep file.

The keep file continues to grow until it is explicitly erased by a DOS
command.

EXAMPLE 1: save student name and score

       T:Well, $NAME$ , you got #SCORE right.
       K: NAME$ !! SCORE
       E:


See also: PROBLEM

LINK - chain to another program file


       L: filename
       L: filename, destination

Most programs you write should be divided into separate files, or modules.
This facilitates program editing and helps keep an organized structure to
your program. The LINK statement is used to transfer control from one program
module to another.  LINK is similar in use to the CHAIN statement of BASIC.
When LINK is executed, the current program is removed from memory and the
linked program is loaded into memory.  All variables are retained from one
module to the next. If you wish to Link to a string variable, see example 3
below.

EXAMPLE 1: link to another program file

       L:CHAPTER7

In the above, the program is assumed to be in file CHAPTER7.PIL.

With LINK you can start the new module at the beginning or at any label
within the module.

EXAMPLE 2: link to a label in another file

       L:CHEMX,Q3

The above links to file CHEMX.PIL, then does an automatic JUMP to label Q3 in
that file.

EXAMPLE 3: link to file name in a string variable, say X$

       X:"L:" !! X$

See also: JUMP

MATCH - compare student response

       M:pattern
       MS:pattern
       MJ:pattern
       MX:expression

MATCH is used to test the answer given by the student to a previous ACCEPT
statement. There are two types of MATCH, pattern matching and numerical
matching. In either case, the result of the MATCH is a YES or a NO. The YES
or NO can subsequently be tested by use of the Y or N conditionals.

PILOT does not make any assumptions about the correctness or incorrectness of
an answer. You can use MATCH equally well to test for correct answers or
anticipated incorrect answers. YES does not necessarily always mean correct
and NO does not necessarily always mean incorrect.

PATTERN MATCHING

MATCH compares the student answer buffer (%B) with the pattern after the
colon on the MATCH statement.  The result is a YES or NO match which can be
tested by the Y or N conditionals.  When comparing, if the student answer
contains the match pattern anywhere within the student answer, it is
considered a YES match.

EXAMPLE 1: simple MATCH

       M:HAT
                student answer: CHATTER gives YES
                student answer: HAT gives YES
                student answer: CAT gives NO

SPECIAL MATCH CHARACTERS

When writing the pattern, you can use the following special characters within
the pattern.

*    matches any one character

&    matches any string of zero or more characters

It can be considered to separate several items which must occur in specific
order but that may have other data between items.

@    separate items which must be present but may be in
         any order

!      separate alternative patterns

%    matches only a space or the start or end of the answer


NEGATION

If the first character of the match pattern is the not character, "^" , then
the sense of the match is inverted. That is, it will yield a YES if the match
pattern is NOT found in the student answer, and will yield a NO if the match
pattern IS found in the student answer.


SPELLING ERRORS

The S modifier can be appended to the MATCH op code.  MS: is sometimes called
MATCH SPELLING.  The Spelling modifier makes the MATCH more liberal in its
comparison. If the student answer is off by only a minor spelling error, then
the MATCH is still YES. A minor spelling error is one wrong letter or two
inverted letters.

EXAMPLE 2: Various MATCH statements.

M:HAT
                          HAT - YES
                          CHATTER - YES

M:%HAT%
                          HAT - YES
                          CHATTER - NO

M:CAT&DOG
                          CATDOG - YES
                          CATS AND DOGS - YES
                          DOGS AND CATS - NO

M:CAT@DOG
                          CATDOG - YES
                          CATS AND DOGS - YES
                          DOGS AND CATS - YES

MS:GREEN
                          GREAN - YES
                          GRENE - YES

MS:CAT!DOG
                          CAT - YES
                          COT - YES
                          DIG - YES

M:H*T
                          HOT - YES
                          HAT - YES
                          HT - NO

M:^DOG
                          DOG - NO
                          CAT - YES

M:RED&BLUE!HOT
                          RED, WHITE, BLUE - YES
                          HOT - YES
                          RED - NO

SYSTEM VARIABLES AFTER A MATCH

There are three system variables set after a pattern match. Each is set to
zero if the pattern did not match, otherwise each is set as follows:

%N  -  alternate answer indicator

%N is the number of the alternate answer which matched when an "!" is used to
separate possible alternate answers.  For example, M:CAT!DOG!HORSE if the
student types CAT, %N=1, if the student types DOG, %N=2, etc.

%M  -  offset of match in student answer

%M is the byte location within the student answer (ie.  subscript within %B)
at which the match began.

%L  -  match length

%L is the number of bytes within the student answer (%B) which matched.

Example:

       M:C&T

If student reply is SCANTY,

       %M=2, %L=4

AUTOMATIC JUMP TO NEXT MATCH

Appending the J modifier to the MATCH op code causes a JUMP to the next MATCH
if this match results in a NO.

NUMERIC MATCH

The MX: statement is used to make numeric comparisons. The argument after the
colon is an expression. The expression is evaluated, if the numeric value of
the expression is true (non-zero), the result of the MATCH is YES. If the
numeric value of the expression is false (0), then the result of the MATCH is
NO.

EXAMPLE 3: numeric matching

        MX: FLO(%B) > 50
        TY:Too big, try again.

        MX: X > 98.3  &  X < 98.9
        TY:Close enough.

See also:  ACCEPT, JUMP, CONDITIONALS

NEW CHARACTER - define char pattern

       N:c . . . / / /       (64 . and / characters)

PILOT uses Ascii character codes 32 through 256 for printable characters. The
ASCII code table defines only the characters from 32 through 127.  This
leaves 128 characters, from 128 to 256, for other uses. These characters are
used in the text modes (modes 0 through 3) for the extended text mode
characters. These include various line drawing characters, mathematical
symbols and foreign characters. In the graphics modes (modes 4 through 6) the
128 extra characters are set aside as user-definable special characters. This
means that you can design your own characters for special type fonts, foreign
languages, or other special symbols.

The special characters should not be confused with character "fonts". Special
characters defined by the N: statement are restricted to the standard 8 by 8
pixel character size. Character fonts, described under the NS: statement, can
be used for smaller or larger character representations.

The NEW CHARACTER command can be used to change the 8 by 8 dot pattern for
any of the 128 changeable characters. Prior to execution of any N: statement
the characters from 128 to 255 have unpredictable display patterns in the
graphics modes.  Once at least one N: statement has been executed, the
characters from 128 to 255 that have not been explicitly changed will have
the same display pattern as the corresponding character in the range 0 to
127.  The N: statement has no effect on the characters displayed in text
modes. In text modes, the characters displayed are always the default text
mode extended character set, as shown in Appendix B.

The letter c shown in the format of N: above stands for any character from
128 to 255. (The EZ editor provides a way to enter characters in that range
into a program.)  It is followed by 64 periods and slash characters.  They
depict the pattern of zero (.) and one (/) bits that will be used to display
the character.  The 64 bits may be given on 8 lines of 8 bits each, to give a
visual picture of the character pattern.  The 64 bits may also be given all
on one line or any desired format that adds up to 64.  Intervening spaces and
new lines are ignored.


CHARACTER EDITOR

Although you could write an N: statement and manually determine the pattern
of dots and slashes, you would normally use the Character Editor included in
the EZ editor. It makes the process of creating character patterns very easy.
EZ also allows you to see your re-defined characters while you are editing
your program if you wish.

See also: The EZ Editor

NEW HEIGHT/WIDTH - set font size


       NH: h,w

The NH: statement may be used to change the default font character cell size.
The font character cell size is used to compute row/column coordinates for
cursor addressing by the "TS:Gc,r" command when in font display mode.

When a font is activated as the current font (see NS: statement) it has a
default character cell height and width, in pixels. This default height and
width are usually set to accommodate the largest character in the font. When
the program executes a TYPE SCREEN with a GOTO command to set the cursor, the
character cell height and width are used to compute the pixel location for
the cursor.

A typical use of NH: is to set both height and width to 1. Thus the command
to set the cursor location has the effect of absolute pixel addressing. Thus
a font character could be written at any pixel on the screen.

EXAMPLE 1: change to pixel addressing

       NH: 1,1

See also: NEW FONT

NEW FONT - set font mode


       NS: variable$
       NS: variable$,c1,c2,c3
       NS:

The NS: statement may be used to set "font display mode". NS: may be executed
only with the screen in display mode 4 or higher. The "variable$" must be a
character string variable which contains the desired character font. In font
display mode all characters typed by the program or entered on the keyboard
are displayed in the type size and style of the active character font.

Character fonts can be used to display text in characters that range in size
up to 24 by 24 pixels, and accommodate an unlimited variety of type styles.

The character font may be one supplied with PILOT or may be one created by
using the Font Editor, described in a later section of this document.

The NS: statement with no parameters after the colon may be used to turn off
font display mode and return to normal text display mode. Font display mode
is also turned off by the mode set command of the TYPE SCREEN statement.

When font display mode is entered the font text cursor is placed in the home
position and color and spacing options are set to the defaults contained in
the font.


FONT COLORS

A character font can define each character in one, two or three colors. So an
individual character can contain as many as three different colored pixels.
This provides for great flexibility in font design for outlines, drop
shadows, etc.  The three colors are numbered 1,2 and 3. Some fonts are
designed with one color only. In this case the one color is normally color 3.

The NS: statement provides for a way to re-map the three colors to any other
three colors. In modes 4 and 5 the three new colors can be from 0 to 3. But
in EGA extended modes (13,14 and 16) the three new colors can be selected
from 0 through 15. So at any one time a character can be displayed in up to
three of the colors supported in the current screen mode.

To re-map the colors use the second form of the NS: statement above. The
values for c1,c2 and c3 are the new color numbers for the three colors.

The foreground color command of the TYPE SCREEN statement and the #n command
of the TYPE statement both provide a means of changing the text color. Both
of these commands set the new value for color number 3 of the font. So for
fonts which are defined in one color, the same commands used when not in font
display mode are used to set the text color in font display mode as well.


HOW TO READ A FONT

To use a font the program must first set up a string variable long enough to
contain the font, and must read the font file into the string variable. By
convention, PILOT font files have a file name suffix of ".PIF". The following
example shows how to read a font file into a string variable.

EXAMPLE 1: read a font file

       D: F$(5000)
       FX: HELV9.PIF
       FI: 0,F$


FONT CURSOR ADDRESSING

Characters are displayed in font mode with proportional spacing. This means
that each character is only as wide as necessary. Also, a character can be
displayed at any pixel boundary, not only at the pre-defined character cells
of normal text. When in font display mode the text cursor is kept in terms of
pixels, not character cells. The cursor is considered to be at the upper left
pixel of the cell in which the next character would be displayed. The XCR and
YCR functions return pixel values in this mode.

Viewports can be used with font display mode, but the viewport boundaries are
still expressed in the character boundaries used for non-font mode. The
result is that viewports are always defined on 8 pixel boundaries though the
characters in the viewport might be displayed at any pixel. Cursor addressing
within a viewport is relative to the home pixel of the viewport (upper left
pixel).

Proportional spacing improves readability and permits more text per line but
it somewhat complicates the issue of cursor row/column addressing.  The GOTO
command of the TS: statement may be used to move the cursor to any screen
position by specifying a row and column coordinate. Since each character is
different size, each font has a default character cell height and width
defined. These values usually represent average character size for the font.
These average sizes are used to position the font text cursor. The cursor is
positioned at the pixel represented by the column and row values multiplied
by the default character cell size.

The NH: statement provides a means of altering the effect of cursor
addressing. With NH: the program can change the values multiplied by the row
and column numbers. The most typical case is to execute the statement  NH:1,1
after executing the NS: statement.  This sets cursor addressing to pixel
coordinates giving the program the ability to address the font text cursor to
an absolute pixel.